<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
  <title>tango.util.Convert</title>
  <link href="./css/style.css" rel="stylesheet" type="text/css"/>
  <!-- <link href="./img/icon.png" rel="icon" type="image/png"/> -->
  <script type="text/javascript" src="./js/jquery.js"></script>
  <script type="text/javascript" src="./js/modules.js"></script>
  <script type="text/javascript" src="./js/quicksearch.js"></script>
  <script type="text/javascript" src="./js/navigation.js"></script>
  <!--<script type="text/javascript" src="./js/jquery.treeview.js"></script>-->
  <script type="text/javascript">
    var g_moduleFQN = "tango.util.Convert";
  </script>
  
</head>
<body>
<div id="content">
  <h1><a href="./htmlsrc/tango.util.Convert.html" class="symbol">tango.util.Convert</a></h1>
  
<div class="summary">This module provides a templated function that performs value-preserving
 conversions between arbitrary types.  This function's behaviour can be
 extended for user-defined types as needed.</div>
<p class="sec_header">License:</p>BSD style: see <a href="http://www.dsource.org/projects/tango/wiki/LibraryLicense">license.txt</a>
<p class="sec_header">Authors:</p>Daniel Keep
<p class="sec_header">Credits:</p>Inspired in part by Andrei Alexandrescu's work on std.conv.
<dl>
<dt class="decl">D <a class="symbol _function" name="to" href="./htmlsrc/tango.util.Convert.html#L133" kind="function" beg="133" end="133">to</a><span class="tparams">(D,S)</span><span class="params">(S <em>value</em>)</span>; <a title="Permalink to this symbol" href="#to" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/tango.util.Convert.html#L133">#</a></dt>
<dt class="decl">D <a class="symbol _function" name="to:2" href="./htmlsrc/tango.util.Convert.html#L134" kind="function" beg="134" end="134">to</a><span class="tparams">(D,S)</span><span class="params">(S <em>value</em>, D <em>default_</em>)</span>; <a title="Permalink to this symbol" href="#to:2" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/tango.util.Convert.html#L134">#</a></dt>
<dd class="ddef">
<div class="summary">Attempts to perform a value-preserving conversion of the given value
 from type S to type D.  If the conversion cannot be performed in any
 context, a compile-time error will be issued describing the types
 involved.  If the conversion fails at run-time because the destination
 type could not represent the value being converted, a
 ConversionException will be thrown.</div>
For example, to convert the string "123" into an equivalent integer
 value, you would use:
<p class="bl"/>
 <pre class="d_code">
<span class="k">auto</span> <span class="i">v</span> = <span class="i">to</span>!(<span class="k">int</span>)(<span class="sl">"123"</span>);
</pre>
<p class="bl"/>
 You may also specify a default value which should be returned in the
 event that the conversion cannot take place:
<p class="bl"/>
 <pre class="d_code">
<span class="k">auto</span> <span class="i">v</span> = <span class="i">to</span>!(<span class="k">int</span>)(<span class="sl">"abc"</span>, <span class="n">456</span>);
</pre>
<p class="bl"/>
 The function will attempt to preserve the input value as exactly as
 possible, given the limitations of the destination format.  For
 instance, converting a floating-point value to an integer will cause it
 to round the value to the nearest integer value.
<p class="bl"/>
 Below is a complete list of conversions between built-in types and
 strings.  Capitalised names indicate classes of types.  Conversions
 between types in the same class are also possible.
<p class="bl"/>
 <pre class="d_code">
<span class="k">bool</span>         &lt;-- <span class="i">Integer</span> (<span class="n">0</span>/!<span class="n">0</span>), <span class="i">Char</span> (<span class="cl">'t'</span>/<span class="cl">'f'</span>), <span class="i">String</span> (<span class="sl">"true"</span>/<span class="sl">"false"</span>)
<span class="i">Integer</span>      &lt;-- <span class="k">bool</span>, <span class="i">Real</span>, <span class="i">Char</span> (<span class="cl">'0'</span>-<span class="cl">'9'</span>), <span class="i">String</span>
<span class="i">Real</span>         &lt;-- <span class="i">Integer</span>, <span class="i">String</span>
<span class="i">Imaginary</span>    &lt;-- <span class="i">Complex</span>
<span class="i">Complex</span>      &lt;-- <span class="i">Integer</span>, <span class="i">Real</span>, <span class="i">Imaginary</span>
<span class="i">Char</span>         &lt;-- <span class="k">bool</span>, <span class="i">Integer</span> (<span class="n">0</span>-<span class="n">9</span>)
<span class="i">String</span>       &lt;-- <span class="k">bool</span>, <span class="i">Integer</span>, <span class="i">Real</span>
</pre>
<p class="bl"/>
 Conversions between arrays and associative arrays are also supported,
 and are done element-by-element.
<p class="bl"/>
 You can add support for value conversions to your types by defining
 appropriate static and instance member functions.  Given a type
 the_type, any of the following members of a type T may be used:
<p class="bl"/>
 <pre class="d_code">
<span class="i">the_type</span> <span class="i">to_the_type</span>();
<span class="k">static</span> <span class="i">T</span> <span class="i">from_the_type</span>(<span class="i">the_type</span>);
</pre>
<p class="bl"/>
 You may also use "camel case" names:
<p class="bl"/>
 <pre class="d_code">
<span class="i">the_type</span> <span class="i">toTheType</span>();
<span class="k">static</span> <span class="i">T</span> <span class="i">fromTheType</span>(<span class="i">the_type</span>);
</pre>
<p class="bl"/>
 Arrays and associative arrays can also be explicitly supported:
<p class="bl"/>
 <pre class="d_code">
<span class="i">the_type</span>[] <span class="i">to_the_type_array</span>();
<span class="i">the_type</span>[] <span class="i">toTheTypeArray</span>();

<span class="k">static</span> <span class="i">T</span> <span class="i">from_the_type_array</span>(<span class="i">the_type</span>[]);
<span class="k">static</span> <span class="i">T</span> <span class="i">fromTheTypeArray</span>(<span class="i">the_type</span>[]);

<span class="i">the_type</span>[<span class="k">int</span>] <span class="i">to_int_to_the_type_map</span>();
<span class="i">the_type</span>[<span class="k">int</span>] <span class="i">toIntToTheTypeMap</span>();

<span class="k">static</span> <span class="i">T</span> <span class="i">from_int_to_the_type_map</span>(<span class="i">the_type</span>[<span class="k">int</span>]);
<span class="k">static</span> <span class="i">T</span> <span class="i">fromIntToTheTypeMap</span>(<span class="i">the_type</span>[<span class="k">int</span>]);
</pre>
<p class="bl"/>
 If you have more complex requirements, you can also use the generic to
 and from templated members:
<p class="bl"/>
 <pre class="d_code">
<span class="i">the_type</span> <span class="i">to</span>(<span class="i">the_type</span>)();
<span class="k">static</span> <span class="i">T</span> <span class="i">from</span>(<span class="i">the_type</span>)(<span class="i">the_type</span>);
</pre>
<p class="bl"/>
 These templates will have the_type explicitly passed to them in the
 template instantiation.
<p class="bl"/>
 Finally, strings are given special support.  The following members will
 be checked for:
<p class="bl"/>
 <pre class="d_code">
<span class="k">char</span>[]  <span class="i">toString</span>();
<span class="k">wchar</span>[] <span class="i">toString16</span>();
<span class="k">dchar</span>[] <span class="i">toString32</span>();
<span class="k">char</span>[]  <span class="i">toString</span>();
</pre>
<p class="bl"/>
 The "toString_" method corresponding to the destination string type will be
 tried first.  If this method does not exist, then the function will
 look for another "toString_" method from which it will convert the result.
 Failing this, it will try "toString" and convert the result to the
 appropriate encoding.
<p class="bl"/>
 The rules for converting to a user-defined type are much the same,
 except it makes use of the "fromUtf8", "fromUtf16", "fromUtf32" and
 "fromString" static methods.</dd>
<dt class="decl">class <a class="symbol _class" name="ConversionException" href="./htmlsrc/tango.util.Convert.html#L179" kind="class" beg="179" end="185">ConversionException</a> : Exception; <a title="Permalink to this symbol" href="#ConversionException" class="symlink">¶</a><a title="Go to the HTML source file" class="srclink" href="./htmlsrc/tango.util.Convert.html#L179">#</a></dt>
<dd class="ddef">
<div class="summary">This exception is thrown when the to template is unable to perform a
 conversion at run-time.  This typically occurs when the source value cannot
 be represented in the destination type.  This exception is also thrown when
 the conversion would cause an over- or underflow.</div>
</dd></dl>
</div>
<div id="footer">
  <p>Copyright &copy; 2007 Daniel Keep.</p>
  <p>Page generated by <a href="http://code.google.com/p/dil">dil</a> on Fri Dec 26 04:04:06 2008. Rendered by <a href="http://code.google.com/p/dil/wiki/Kandil">kandil</a>.</p>
</div>
</body>
</html>